volt/docs/cli-reference.md

Volt CLI Reference

Complete command reference for Volt. Generated from actual --help output.

Global Flags

Available on every command:

Flag	Short	Type	Default	Description
--help	-h			Show help for the command
--output	-o	string	table	Output format: table, json, yaml, wide
--quiet	-q			Suppress non-essential output
--debug				Enable debug logging to stderr
--no-color				Disable colored output
--config		string	/etc/volt/config.yaml	Path to config file
--timeout		int	30	Command timeout in seconds
--backend		string	auto-detect	Container backend: systemd

---

Workload Commands

volt container — Voltainer (systemd-nspawn)

Manage containers built on systemd-nspawn. Alias: con.

volt container create

Create a new container from an image.

volt container create [flags]

Flag	Short	Type	Description
--name		string	Container name (required)
--image		string	Image name or path (required)
--start			Start container after creation
--memory		string	Memory limit (e.g., 512M, 2G)
--cpu		string	CPU shares/quota
--network		string	Network bridge (default: volt0)
--env	-e	strings	Environment variables
--volume	-v	strings	Volume mounts (host:container)

volt container create --name web --image ubuntu:24.04 --start
volt container create --name db --image debian:bookworm --memory 2G --start
volt container create --name api --image ubuntu:24.04 --cpu 200 --memory 1G -e "NODE_ENV=production" --start

volt container list

List containers. Alias: ls.

volt container list
volt container list -o json
volt container ls

volt container start

Start a stopped container.

volt container start web

volt container stop

Stop a running container (graceful SIGTERM, then SIGKILL).

volt container stop web

volt container restart

Restart a container.

volt container restart web

volt container kill

Send a signal to a container (default: SIGKILL).

Flag	Type	Default	Description
--signal	string	SIGKILL	Signal to send

volt container kill web
volt container kill --signal SIGTERM web

volt container exec

Execute a command inside a running container.

volt container exec web -- nginx -t
volt container exec web -- ls -la /var/log
volt container exec db -- psql -U postgres

volt container shell

Open an interactive shell in a container (shortcut for exec /bin/sh).

volt container shell web

volt container attach

Attach to a container's main process (stdin/stdout/stderr).

volt container attach web

volt container inspect

Show detailed container configuration and state.

volt container inspect web
volt container inspect web -o json

volt container logs

View container logs from the systemd journal.

Flag	Short	Type	Description
--follow	-f		Follow log output
--tail		int	Number of lines from end

volt container logs web
volt container logs -f web
volt container logs --tail 50 web

volt container cp

Copy files between host and container. Use container_name:/path for container paths.

volt container cp ./config.yaml web:/etc/app/config.yaml
volt container cp web:/var/log/app.log ./app.log

volt container rename

Rename a container.

volt container rename old-name new-name

volt container update

Update resource limits on a running container.

Flag	Type	Description
--memory	string	New memory limit
--cpu	string	New CPU quota

volt container update web --memory 1G
volt container update web --cpu 200

volt container export

Export container filesystem as a tarball.

Flag	Short	Type	Description
--output	-O	string	Output file path

volt container export web
volt container export web --output web-backup.tar.gz

volt container delete

Delete a container. Alias: rm.

Flag	Short	Description
--force	-f	Force delete (stop if running)

volt container delete web
volt container rm web
volt container delete -f web

---

volt vm — Voltvisor (KVM)

Create, manage, and destroy virtual machines.

volt vm create

Create a new VM.

Flag	Short	Type	Default	Description
--image	-i	string	volt/server	VM image
--cpu	-c	int	1	CPU cores
--memory	-m	string	256M	Memory
--kernel	-k	string	server	Kernel profile (server|desktop|rt|minimal|dev)
--network	-n	string	default	Network name
--attach		strings		Attach storage (repeatable)
--env	-e	strings		Environment variables
--ode-profile		string		ODE profile for desktop VMs

volt vm create myvm
volt vm create db-primary -c 4 -m 8G -i armoredgate/ubuntu-24.04
volt vm create rt-worker -c 2 -m 4G -k rt

volt vm list

List all VMs.

volt vm list
volt vm list -o json

volt vm start

Start a VM.

volt vm start myvm

volt vm stop

Stop a VM (ACPI shutdown).

volt vm stop myvm

volt vm destroy

Destroy a VM and its resources.

volt vm destroy myvm

volt vm ssh

SSH into a VM by name.

volt vm ssh myvm

volt vm exec

Execute a command inside a VM.

volt vm exec myvm -- uname -a

volt vm attach

Attach storage to a VM.

volt vm attach myvm /path/to/disk.qcow2

---

volt desktop — VDI Management

Create and manage desktop VMs with remote display.

volt desktop create

Create a desktop VM.

volt desktop create --name dev-workstation

volt desktop list

List desktop VMs.

volt desktop list

volt desktop connect

Connect to a desktop VM via remote display.

volt desktop connect dev-workstation

---

volt workload — Unified Workload Management

Manage workloads across Voltainer containers, hybrid-native processes, and Voltvisor VMs. Alias: wl.

The workload abstraction layer provides a single interface for lifecycle operations regardless of backend type and execution mode. Each command auto-detects whether a workload is a container, hybrid-native, or VM and delegates to the appropriate backend.

Execution Modes:

Mode	Description
container	Voltainer (systemd-nspawn) — full OS container isolation
hybrid-native	Landlock LSM + seccomp-bpf + cgroups v2 — no namespace overhead
hybrid-kvm	Voltvisor (KVM) micro-VM — hardware-level isolation
hybrid-emulated	QEMU user-mode emulation — cross-arch workloads

Used by the Volt Edge wake proxy and Sleep Controller for scale-to-zero operations. Supports freeze/thaw for sub-second wake times and full start/stop for maximum resource savings.

volt workload create

Create a new workload.

volt workload create --name my-app --mode hybrid-native --manifest app.toml

volt workload list

List all workloads with state and mode.

volt workload list

volt workload status

Show workload status (state, mode, uptime, resources).

volt workload status my-app

volt workload start

Start a stopped workload.

volt workload start my-app

volt workload stop

Stop a running or frozen workload.

volt workload stop my-app

volt workload restart

Restart a workload.

volt workload restart my-app

volt workload freeze

Freeze a running workload (preserve memory state for sub-second wake).

volt workload freeze my-app

volt workload thaw

Thaw a frozen workload (resume from preserved memory state).

volt workload thaw my-app

volt workload toggle

Toggle workload between execution modes.

volt workload toggle my-app --target-mode hybrid-native

volt workload inspect

Show detailed workload info.

volt workload inspect my-app

volt workload manifest

Validate a workload manifest.

volt workload manifest app.toml

---

volt service — systemd Services

Manage systemd services. Alias: svc.

volt service create

Create a new systemd service unit file.

Flag	Type	Default	Description
--name	string		Service name (required)
--exec	string		Command to execute (required)
--user	string		Run as user
--group	string		Run as group
--workdir	string		Working directory
--restart	string	on-failure	Restart policy: no|on-failure|always|on-success
--after	string		Start after this unit
--description	string		Service description
--env	strings		Environment variables (KEY=VALUE)
--enable			Enable service after creation
--start			Start service after creation

volt service create --name myapp --exec /usr/bin/myapp
volt service create --name myapi --exec "/usr/bin/myapi --port 8080" \
  --user www-data --restart always --enable --start
volt service create --name worker --exec /usr/bin/worker \
  --after postgresql.service --restart on-failure

volt service list

List services. Alias: ls.

Flag	Description
--all	Show all services (including inactive)

volt service list
volt service list --all
volt service list -o json

volt service status

Show service status.

volt service status nginx

volt service start

Start a service.

volt service start nginx

volt service stop

Stop a service.

volt service stop nginx

volt service restart

Restart a service.

volt service restart nginx

volt service reload

Reload service configuration (sends SIGHUP).

volt service reload nginx

volt service enable

Enable a service to start at boot.

Flag	Description
--now	Also start the service now

volt service enable nginx
volt service enable nginx --now

volt service disable

Disable a service from starting at boot.

Flag	Description
--now	Also stop the service now

volt service disable nginx
volt service disable nginx --now

volt service inspect

Show detailed service properties.

volt service inspect nginx
volt service inspect nginx -o json

volt service show

Show service unit file contents. Alias: cat.

volt service show nginx
volt service cat nginx

volt service edit

Open a service unit file in $EDITOR, then daemon-reload.

Flag	Type	Description
--inline	string	Apply inline override without opening editor

volt service edit nginx
volt service edit myapp --inline "Restart=always"

volt service deps

Show service dependency tree.

volt service deps nginx
volt service deps sshd

volt service logs

View service logs from the systemd journal.

Flag	Short	Type	Description
--follow	-f		Follow log output
--tail		int	Number of lines from end
--since		string	Show entries since (e.g., "1 hour ago")

volt service logs nginx
volt service logs -f nginx
volt service logs --tail 100 nginx

volt service mask

Mask a service (prevent starting entirely).

volt service mask bluetooth

volt service unmask

Unmask a service.

volt service unmask bluetooth

volt service template

Generate a systemd unit file from a template type.

Templates: simple, oneshot, forking, notify, socket.

Flag	Type	Description
--name	string	Service name (required)
--exec	string	Command to execute (required)
--description	string	Service description
--user	string	Run as user

volt service template simple --name myapp --exec /usr/bin/myapp
volt service template oneshot --name backup --exec /usr/local/bin/backup.sh
volt service template notify --name myapi --exec /usr/bin/myapi

volt service delete

Delete a service (stop, disable, remove unit file). Alias: rm.

volt service delete myapp

---

volt task — Scheduled Tasks

Manage scheduled tasks using systemd timers. Alias: timer.

volt task create

Create a timer + service pair.

Flag	Type	Description
--name	string	Task name (required)
--exec	string	Command to execute (required)
--calendar	string	systemd calendar syntax
--interval	string	Interval (e.g., 15min, 1h, 30s)
--description	string	Task description
--user	string	Run as user
--persistent		Run missed tasks on boot
--enable		Enable timer after creation

Calendar syntax examples:

• daily, weekly, monthly, hourly, minutely
• *-*-* 03:00:00 — every day at 3 AM
• Mon *-*-* 09:00 — every Monday at 9 AM
• *:0/15 — every 15 minutes

volt task create --name backup --exec /usr/local/bin/backup.sh --calendar "daily"
volt task create --name cleanup --exec "/usr/bin/find /tmp -mtime +7 -delete" --calendar "*:0/30"
volt task create --name report --exec /opt/report.sh --calendar "Mon *-*-* 09:00" --enable
volt task create --name healthcheck --exec "curl -sf http://localhost/health" --interval 5min --enable

volt task list

List scheduled tasks. Alias: ls.

Flag	Description
--all	Show all timers (including inactive)

volt task list
volt task list --all

volt task run

Run a task immediately (one-shot, regardless of schedule).

volt task run backup

volt task status

Show task timer status (next run, last run, etc.).

volt task status backup

volt task logs

View task execution logs.

Flag	Short	Type	Description
--follow	-f		Follow log output
--tail		int	Number of lines from end

volt task logs backup
volt task logs -f backup

volt task enable

Enable a scheduled task.

volt task enable backup

volt task disable

Disable a scheduled task.

volt task disable backup

volt task edit

Edit a task's timer or service file in $EDITOR.

volt task edit backup

volt task delete

Delete a scheduled task. Alias: rm.

volt task delete backup

---

Infrastructure Commands

volt net — Networking

Manage networks, bridges, firewall rules, DNS, port forwarding, and policies. Alias: network.

volt net create

Create a network.

Flag	Type	Default	Description
--name	string		Network name
--subnet	string	10.0.0.0/24	Subnet CIDR
--no-nat			Disable NAT

volt net create --name mynet --subnet 10.0.1.0/24
volt net create --name isolated --subnet 172.20.0.0/16 --no-nat

volt net list

List networks. Alias: ls.

volt net list
volt net list -o json

volt net inspect

Show detailed network information.

volt net inspect mynet

volt net delete

Delete a network. Alias: rm.

volt net delete mynet

volt net connect

Connect an interface to a network.

volt net connect backend web-frontend

volt net disconnect

Disconnect an interface from its network.

volt net disconnect web-frontend

volt net status

Show network overview (bridges, interfaces, IPs).

volt net status

volt net bridge list

List bridge interfaces. Alias: ls.

volt net bridge list

volt net bridge create

Create a bridge.

Flag	Type	Description
--subnet	string	IP/CIDR for bridge

volt net bridge create mybridge --subnet 10.50.0.0/24

volt net bridge delete

Delete a bridge.

volt net bridge delete mybridge

volt net firewall list

List firewall rules. Alias: ls.

volt net firewall list

volt net firewall add

Add a firewall rule.

Flag	Type	Default	Description
--name	string		Rule name
--source	string	any	Source IP/CIDR
--dest	string	any	Destination IP/CIDR
--port	string		Destination port
--proto	string	tcp	Protocol (tcp/udp)
--action	string		Action (accept/drop)

volt net firewall add --name allow-web \
  --source 10.0.0.0/24 --dest 10.0.1.0/24 --port 80 --proto tcp --action accept
volt net firewall add --name block-ssh \
  --source any --dest 10.0.0.5 --port 22 --proto tcp --action drop

volt net firewall delete

Delete a firewall rule by name.

volt net firewall delete --name allow-web

volt net firewall flush

Flush all firewall rules.

volt net firewall flush

volt net dns list

List DNS servers.

volt net dns list

volt net port list

List port forwards.

volt net port list

volt net policy create

Create a network policy.

Flag	Type	Description
--name	string	Policy name
--from	string	Source workload
--to	string	Destination workload
--port	string	Destination port
--action	string	Action (allow/deny)

volt net policy create --name web-to-db \
  --from web --to database --port 5432 --action allow

volt net policy list

List network policies. Alias: ls.

volt net policy list

volt net policy delete

Delete a network policy.

volt net policy delete --name web-to-db

volt net policy test

Test if traffic would be allowed by current policies.

Flag	Type	Description
--from	string	Source workload
--to	string	Destination workload
--port	string	Destination port

volt net policy test --from web --to database --port 5432

volt net vlan list

List VLANs.

volt net vlan list

---

volt ingress — Reverse Proxy

Manage the built-in reverse proxy for routing external traffic to workloads. Aliases: gateway, gw.

Routes are matched by hostname and optional path prefix. Supports automatic TLS via ACME (Let's Encrypt) or manual certificates.

See also: Ingress Proxy in the networking docs.

volt ingress create

Create a new ingress route.

Flag	Type	Description
--name	string	Route name
--hostname	string	Hostname to match
--path	string	Path prefix to match
--backend	string	Backend address (container:port or IP:port)
--tls	string	TLS mode: auto, manual, passthrough
--cert	string	TLS certificate file (for manual mode)
--key	string	TLS key file (for manual mode)
--timeout	int	Backend timeout in seconds (default: 30)

volt ingress create --name web --hostname app.example.com --backend web:8080
volt ingress create --name api --hostname api.example.com --path /v1 --backend api:3000 --tls auto
volt ingress create --name static --hostname cdn.example.com --backend static:80 \
  --tls manual --cert /etc/certs/cdn.pem --key /etc/certs/cdn.key

volt ingress list

List ingress routes. Alias: ls.

volt ingress list
volt ingress list -o json

volt ingress status

Show ingress proxy status.

volt ingress status

volt ingress delete

Delete an ingress route. Alias: rm.

Flag	Type	Description
--name	string	Route name to delete

volt ingress delete --name web

volt ingress serve

Start the ingress reverse proxy in the foreground.

Flag	Type	Default	Description
--http-port	int	80	HTTP listen port
--https-port	int	443	HTTPS listen port

For production use, run as a systemd service:

systemctl enable --now volt-ingress.service

volt ingress serve
volt ingress serve --http-port 8080 --https-port 8443

volt ingress reload

Reload route configuration without downtime. Routes are re-read from the store and applied to the running proxy.

volt ingress reload

---

volt volume — Persistent Storage

Manage persistent storage volumes. Alias: vol.

volt volume create

Create a volume.

Flag	Type	Description
--name	string	Volume name (required)
--size	string	Size for file-backed ext4 (e.g., 1G, 500M)

volt volume create --name mydata
volt volume create --name mydata --size 10G

volt volume list

List volumes. Alias: ls.

volt volume list

volt volume inspect

Show detailed volume information.

volt volume inspect mydata

volt volume attach

Attach a volume to a workload.

Flag	Type	Description
--target	string	Target workload name
--mount	string	Mount path inside workload

volt volume attach mydata --target web --mount /data

volt volume detach

Detach a volume from a workload.

volt volume detach mydata

volt volume resize

Resize a volume.

Flag	Type	Description
--size	string	New size (required)

volt volume resize mydata --size 20G

volt volume snapshot

Create a volume snapshot.

Flag	Type	Description
--name	string	Snapshot name

volt volume snapshot mydata --name pre-migration

volt volume backup

Backup a volume.

volt volume backup mydata

volt volume delete

Delete a volume. Alias: rm.

volt volume delete mydata

---

volt image — Image Management

Manage container and VM images. Alias: img.

volt image list

List local images. Alias: ls.

volt image list
volt image list -o json

volt image pull

Pull a distribution image using debootstrap.

volt image pull ubuntu:24.04
volt image pull debian:bookworm

volt image build

Build an image from a spec file.

Flag	Short	Type	Default	Description
--file	-f	string	Voltfile	Build spec file path
--tag	-t	string		Image tag name (required)
--no-cache				Build without cache

volt image build -f spec.yaml -t myimage
volt image build -f Voltfile -t webserver

volt image inspect

Show detailed image information.

volt image inspect ubuntu_24.04

volt image import

Import an image from a tarball.

Flag	Type	Description
--tag	string	Image tag name (required)

volt image import rootfs.tar.gz --tag myimage

volt image export

Export an image as a tarball.

volt image export ubuntu_24.04

volt image tag

Tag an image.

volt image tag ubuntu_24.04 my-base

volt image push

Push an image to a registry.

volt image push myimage

volt image delete

Delete an image. Alias: rm.

volt image delete myimage

---

volt cas — Stellarium CAS

Content-addressed storage operations.

volt cas status

Show CAS store statistics (object count, total size, dedup ratio).

volt cas status

volt cas info

Show information about a specific CAS object by hash.

volt cas info abc123def456

volt cas build

Hash a directory tree, store each file as a CAS object, and create a manifest.

volt cas build /path/to/rootfs

volt cas verify

Verify integrity of all CAS objects (hash matches filename).

volt cas verify

volt cas gc

Garbage collect unreferenced objects.

Flag	Description
--dry-run	Show what would be deleted without deleting

volt cas gc --dry-run
volt cas gc

volt cas dedup

Run deduplication analysis.

volt cas dedup

volt cas pull

Pull an object from remote CAS.

volt cas pull abc123def456

volt cas push

Push an object to remote CAS.

volt cas push /path/to/object

volt cas sync

Sync local CAS store with remote.

volt cas sync

---

volt registry — OCI Container Registry

Manage the built-in OCI Distribution Spec compliant container registry. Alias: reg.

The registry stores all blobs in Stellarium CAS — the SHA-256 digest IS the CAS address. Manifests and tags are indexed alongside the CAS store.

Licensing: Pull is free for all tiers. Push requires a Pro license.

See also: Registry for full documentation.

volt registry serve

Start the OCI registry server in the foreground.

Flag	Type	Default	Description
--port	int	5000	Listen port
--tls			Enable TLS
--cert	string		TLS certificate file
--key	string		TLS key file
--public		true	Allow anonymous pull
--read-only			Read-only mode (pull only)

For production use, run as a systemd service:

systemctl enable --now volt-registry.service

volt registry serve
volt registry serve --port 5000
volt registry serve --port 5000 --tls --cert /etc/volt/certs/reg.pem --key /etc/volt/certs/reg.key

volt registry status

Show registry status and statistics.

volt registry status
volt registry status -o json

volt registry list

List all repositories and their tags. Alias: ls.

volt registry list
volt registry list -o json

volt registry gc

Garbage collect unreferenced registry blobs.

Flag	Description
--dry-run	Show what would be deleted without deleting

volt registry gc --dry-run
volt registry gc

volt registry token

Generate a bearer token for authenticating with the registry.

Tokens are HMAC-SHA256 signed and include an expiration time. Use --push to generate a token with push (write) access.

Flag	Type	Default	Description
--push			Generate token with push (write) access
--expiry	string	24h	Token expiry duration (e.g., 24h, 7d)

volt registry token
volt registry token --push
volt registry token --push --expiry 7d

---

volt snapshot — Workload Snapshots

Capture and restore point-in-time snapshots of workload filesystems.

Snapshots are lightweight CAS-based captures that can be restored instantly via hard-link assembly. Ideal for pre-deploy snapshots, experimentation, and quick rollback.

volt snapshot create

Create a snapshot of a workload's filesystem.

Only changed files since the last snapshot produce new CAS blobs, making snapshots extremely fast and space-efficient.

Flag	Type	Description
--notes	string	Notes for the snapshot
--tags	strings	Tags (comma-separated)

volt snapshot create my-app
volt snapshot create my-app --notes "before v2.1 deploy"
volt snapshot create my-app --tags "pre-release,v2.1"

volt snapshot list

List snapshots for a workload.

Flag	Type	Default	Description
--limit	int	20	Maximum results to show

volt snapshot list my-app
volt snapshot list my-app -o json

volt snapshot restore

Restore a workload's rootfs from a point-in-time snapshot.

By default, restores to the original rootfs location (overwriting current state). Use --target to restore to a different location.

Flag	Type	Description
--target	string	Target directory (default: original path)
--force		Overwrite existing target

volt snapshot restore my-app-20260619-143052-snapshot
volt snapshot restore my-app-20260619-143052-snapshot --target /tmp/restore-test
volt snapshot restore my-app-20260619-143052-snapshot --force

volt snapshot delete

Delete a snapshot.

volt snapshot delete my-app-20260619-143052-snapshot

---

volt qemu — QEMU Profile Management

Manage purpose-built QEMU compilations stored in Stellarium CAS.

Each profile contains only the QEMU binary, shared libraries, and firmware needed for a specific use case, maximizing CAS deduplication.

Profiles:

Profile	Description
kvm-linux	Headless Linux KVM guests (virtio-only, no TCG)
kvm-uefi	Windows/UEFI KVM guests (VNC, USB, TPM, OVMF)
emulate-x86	x86 TCG emulation (legacy OS, SCADA, nested)
emulate-foreign	Foreign arch TCG (ARM, RISC-V, MIPS, PPC)

volt qemu list

List available QEMU profiles. Alias: ls.

volt qemu list
volt qemu list -o json

volt qemu status

Show detailed QEMU profile status including CAS references.

volt qemu status

volt qemu resolve

Assemble a QEMU profile from CAS. Downloads and links all required binaries, libraries, and firmware for the specified profile.

volt qemu resolve kvm-linux
volt qemu resolve emulate-x86

volt qemu test

Run a smoke test on a QEMU profile. Verifies the profile works by running --version and optionally booting a minimal test payload.

volt qemu test kvm-linux
volt qemu test emulate-x86

---

Observability Commands

volt ps — Unified Process Listing

Show all running workloads in one view. Alias: processes.

volt ps [filter] [flags]

Filters (positional): containers (con, container), vms (vm), services (svc, service)

Flag	Description
--all	Show all workloads (including stopped)

volt ps                    # All running workloads
volt ps --all              # Include stopped
volt ps containers         # Only containers
volt ps vms                # Only VMs
volt ps services           # Only services
volt ps -o json            # JSON output
volt ps -o wide            # All columns

volt ps Subcommands

volt ps also provides quick lifecycle operations:

volt ps start <name>       # Start a workload
volt ps stop <name>        # Stop a workload
volt ps restart <name>     # Restart a workload
volt ps kill <name>        # Kill a workload
volt ps inspect <name>     # Inspect a workload

---

volt logs — Unified Logging

View logs for any workload. Auto-detects type from the systemd journal.

Flag	Short	Type	Description
--follow	-f		Follow log output
--tail		int	Number of lines from end
--since		string	Show entries since (e.g., "1 hour ago")
--until		string	Show entries until
--type		string	Filter by type: container, vm, service
--priority		string	Filter by priority: emerg, alert, crit, err, warning, notice, info, debug
--all			Show all workload logs
--json			Output in JSON format

volt logs nginx                            # Auto-detect type
volt logs -f nginx                         # Follow
volt logs --tail 100 nginx                 # Last 100 lines
volt logs --since "1 hour ago" nginx       # Time filter
volt logs --type container web             # Explicit type
volt logs --priority err --all             # All errors

---

volt top — Resource Usage

Show CPU, memory, and process counts for all workloads.

Filters (positional): containers, vms, services

Flag	Type	Default	Description
--sort	string	name	Sort by: cpu, mem, name, pids

volt top                   # All workloads
volt top containers        # Only containers
volt top --sort cpu        # Sort by CPU
volt top --sort mem        # Sort by memory

---

volt events — Event Stream

Stream real-time events from the platform via the systemd journal.

Flag	Short	Type	Default	Description
--follow	-f		true	Follow event stream
--type		string		Filter: container, vm, service, task
--since		string		Show events since

volt events                        # Follow all events
volt events --type container       # Container events only
volt events --since "1 hour ago"   # Recent events
volt events --no-follow            # Show and exit

---

Composition & Orchestration

volt compose — Declarative Stacks

Manage multi-service stacks from volt-compose.yaml files.

Flag	Short	Type	Description
--file	-f	string	Compose file path
--project		string	Project name override

volt compose up

Create and start all services.

Flag	Short	Description
--detach	-d	Run in background
--build		Build images before starting
--force-recreate		Force recreate services

volt compose up
volt compose up -d
volt compose -f production.yaml up -d
volt compose up --build

volt compose down

Stop and remove all services.

Flag	Description
--volumes	Also remove created volumes

volt compose down
volt compose down --volumes

volt compose ps

List services in the compose stack.

volt compose ps

volt compose logs

View logs for compose services.

Flag	Type	Description
--follow		Follow log output
--tail	int	Number of lines from end

volt compose logs
volt compose logs --follow
volt compose logs api

volt compose start

Start existing services (without recreating).

volt compose start

volt compose stop

Stop running services (without removing).

volt compose stop

volt compose restart

Restart services.

volt compose restart

volt compose exec

Execute a command in a compose service.

volt compose exec myservice -- ls -la
volt compose exec web -- /bin/sh

volt compose build

Build images defined in the compose file.

volt compose build
volt compose build web

volt compose pull

Pull images defined in the compose file.

volt compose pull

volt compose config

Validate and display the resolved compose file.

volt compose config

volt compose top

Show resource usage for compose services.

volt compose top

volt compose events

Stream events from compose services.

Flag	Default	Description
--follow	true	Follow event stream

volt compose events

---

volt deploy — Deployment Strategies

Deploy workloads using zero-downtime strategies. Alias: dp.

Volt deploy coordinates updates across container instances using CAS (content-addressed storage) for image management. Each instance is updated to a new CAS ref, with health verification and automatic rollback on failure.

Strategies:

• rolling — Update instances one-by-one with health checks
• canary — Route a percentage of traffic to a new instance first

volt deploy rolling

Perform a rolling update.

volt deploy rolling web-app --image sha256:def456

volt deploy canary

Perform a canary deployment.

volt deploy canary api-svc --image sha256:new --weight 10

volt deploy status

Show active deployments.

volt deploy status

volt deploy rollback

Rollback to previous version.

volt deploy rollback web-app

volt deploy history

Show deployment history.

volt deploy history web-app

---

volt cluster — Multi-Node

Manage cluster nodes.

Flag	Type	Default	Description
--cluster	string	default	Cluster name
--kubeconfig	string		Path to kubeconfig

volt cluster status

Show cluster overview.

volt cluster status

volt cluster node list

List cluster nodes. Alias: ls.

volt cluster node list

volt cluster node add

Add nodes to the cluster.

Flag	Short	Type	Default	Description
--count	-c	int	1	Number of nodes
--cpu		int	1	CPUs per node
--memory	-m	string	512M	Memory per node
--image	-i	string	volt/k8s-node	Node image
--parallel		int	10	Parallel creation

volt cluster node add --count 10 --memory 512M
volt cluster node add -c 3 --cpu 2 -m 2G

volt cluster node drain

Drain a node for maintenance.

volt cluster node drain volt-node-default-0001

volt cluster node remove

Remove a node from the cluster.

volt cluster node remove volt-node-default-0001

---

volt gitops — GitOps Pipelines

Manage GitOps pipelines that automatically deploy workloads when code is pushed to a Git repository. Alias: go.

Supports GitHub, GitLab, Bitbucket (webhooks) and SVN (polling). Each pipeline links a repository branch to a Volt workload — pushes to the tracked branch trigger automatic clone-and-deploy.

See also: GitOps for full documentation.

volt gitops create

Create a new GitOps pipeline linking a Git repository to a Volt workload.

When a push is detected on the tracked branch (via webhook or SVN polling), the pipeline will:

1. Clone or pull the repository
2. Look for volt-manifest.yaml or Voltfile in the repo root
3. Deploy/update the workload accordingly
4. Log the result

Flag	Type	Default	Description
--name	string		Pipeline name (required)
--repo	string		Repository URL (required)
--provider	string		Git provider: github, gitlab, bitbucket, svn (required)
--branch	string	main	Branch to track
--workload	string		Target workload name (required)
--secret	string		Webhook HMAC secret for signature validation
--poll-interval	int	60	SVN poll interval in seconds

volt gitops create --name web-app --repo https://github.com/org/repo \
  --provider github --branch main --workload web --secret my-webhook-secret
volt gitops create --name api --repo https://gitlab.com/org/api \
  --provider gitlab --branch develop --workload api-svc
volt gitops create --name legacy --repo svn://svn.example.com/trunk \
  --provider svn --branch trunk --workload legacy-app

volt gitops list

List all configured GitOps pipelines. Alias: ls.

volt gitops list
volt gitops list -o json

volt gitops status

Show all pipelines with last deploy status.

volt gitops status

volt gitops serve

Start the webhook receiver HTTP server in the foreground.

The server listens for push events from GitHub, GitLab, and Bitbucket, and polls SVN repositories for revision changes.

Flag	Type	Default	Description
--port	int	9090	HTTP listen port

Endpoints:

• POST /hooks/github — GitHub push webhooks
• POST /hooks/gitlab — GitLab push webhooks
• POST /hooks/bitbucket — Bitbucket push webhooks
• GET /healthz — Health check

For production use, install and run as a systemd service:

volt gitops install-service
systemctl enable --now volt-gitops.service

volt gitops serve
volt gitops serve --port 9090

volt gitops sync

Manually trigger a sync/deploy for a pipeline.

Flag	Type	Description
--name	string	Pipeline name to sync

volt gitops sync --name web-app

volt gitops logs

Show deploy history for a pipeline.

Flag	Type	Default	Description
--name	string		Pipeline name
--limit	int	20	Number of entries to show

volt gitops logs --name web-app
volt gitops logs --name web-app --limit 50

volt gitops delete

Delete a GitOps pipeline. Alias: rm.

Flag	Type	Description
--name	string	Pipeline name to delete

volt gitops delete --name web-app

volt gitops install-service

Install the volt-gitops systemd service for production use.

sudo volt gitops install-service
systemctl enable --now volt-gitops.service

---

Security & Governance

volt rbac — Role-Based Access Control

Manage roles, permissions, and user assignments.

RBAC controls who can perform which operations on the Volt platform. Roles define sets of permissions, and users/groups are assigned to roles.

Built-in roles: admin, operator, deployer, viewer

volt rbac init

Initialize RBAC configuration.

volt rbac init

volt rbac role list

List available roles.

volt rbac role list

volt rbac user assign

Assign a user to a role.

volt rbac user assign karl admin

volt rbac check

Check if a user has a specific permission.

volt rbac check karl containers.create

---

volt audit — Operational Audit Log

Query, verify, and manage the Volt operational audit log.

The audit log records every CLI and API action with structured JSON entries including who, what, when, where, and result. Entries are optionally signed (HMAC-SHA256) for tamper evidence.

Log location: /var/log/volt/audit.log

volt audit search

Search audit log entries.

volt audit search --user karl --action deploy --since 24h

volt audit tail

Show recent audit entries (or follow).

volt audit tail
volt audit tail -f

volt audit verify

Verify audit log integrity.

volt audit verify

volt audit stats

Show audit log statistics.

volt audit stats

volt audit export

Export audit data for compliance.

volt audit export

---

volt security — Security Profiles & Auditing

Security commands for managing Landlock/seccomp profiles and auditing the system security posture.

volt security profile list

List available security profiles.

volt security profile list

volt security profile show

Show details of a security profile.

volt security profile show webserver

volt security audit

Audit system security posture.

volt security audit

volt security scan

Scan for vulnerabilities.

volt security scan

volt security keys

Manage encryption keys.

volt security keys

volt security luks-status

Show LUKS full-disk encryption status.

volt security luks-status

volt security luks-check

Check if LUKS encryption is active (exit code).

volt security luks-check

---

Monitoring

volt health — Continuous Health Monitoring

Configure and manage continuous health checks for Volt workloads.

The health daemon monitors workloads with HTTP, TCP, or exec health checks and can automatically restart workloads that become unhealthy. Unlike deploy-time health checks, the health daemon runs continuously.

volt health configure

Configure health check for a workload.

volt health configure web-app --http /healthz --port 8080 --interval 30s
volt health configure db --tcp --port 5432 --interval 15s --auto-restart

volt health list

List configured health checks.

volt health list

volt health status

Show health status of monitored workloads.

volt health status web-app

volt health check

Run an immediate health check.

volt health check web-app

volt health remove

Remove health check for a workload.

volt health remove web-app

---

volt webhook — Event Notifications

Configure webhook endpoints that receive notifications when events occur.

Supported events: deploy, deploy.fail, crash, health.fail, health.ok, scale, restart, create, delete

Supported formats: json (default), slack

volt webhook add

Add a webhook endpoint.

volt webhook add https://hooks.slack.com/xxx --events deploy,crash --name prod-slack --format slack
volt webhook add https://api.pagerduty.com/... --events crash,health.fail --name pagerduty

volt webhook list

List configured webhooks.

volt webhook list

volt webhook test

Send a test notification to a webhook.

volt webhook test prod-slack

volt webhook remove

Remove a webhook.

volt webhook remove prod-slack

---

System Commands

volt daemon — Daemon Management

Manage the volt platform daemon (voltd).

volt daemon status         # Show daemon status
volt daemon start          # Start daemon
volt daemon stop           # Stop daemon
volt daemon restart        # Restart daemon
volt daemon reload         # Reload configuration
volt daemon config         # Show daemon configuration

---

volt system — Platform Information

volt system info           # Platform info (OS, kernel, CPU, memory, disk)
volt system health         # Health check all subsystems
volt system update         # Check for updates
volt system backup         # Backup config and state
volt system restore <file> # Restore from backup
volt system reset --confirm  # Factory reset (destructive!)

---

volt config — Configuration

volt config show                              # Show current config
volt config get runtime.default_memory        # Get a value
volt config set runtime.default_memory 512M   # Set a value
volt config edit                              # Open in $EDITOR
volt config validate                          # Validate config file
volt config reset                             # Reset to defaults

---

volt tune — Performance Tuning

volt tune show

Show current tuning overview.

volt tune show

volt tune profile

Manage tuning profiles.

volt tune profile list              # List available profiles
volt tune profile show web-server   # Show profile settings
volt tune profile apply web-server  # Apply a profile

volt tune sysctl

Manage sysctl parameters.

Subcommand	Description
list	List all sysctl parameters
get <key>	Get a value
set <key> <value>	Set a value

Flag (set)	Description
--persist	Persist across reboots

Flag (list)	Type	Description
--filter	string	Filter by keyword

volt tune sysctl list
volt tune sysctl list --filter net
volt tune sysctl get net.ipv4.ip_forward
volt tune sysctl set net.ipv4.ip_forward 1
volt tune sysctl set vm.swappiness 10 --persist

volt tune cpu

CPU tuning.

volt tune cpu governor                 # Show current governor
volt tune cpu governor performance     # Set governor

volt tune memory

Memory tuning.

volt tune memory show                  # Show memory settings
volt tune memory limit <workload> --max 4G
volt tune memory hugepages --enable --size 2M --count 4096

volt tune io

I/O tuning.

volt tune io show                      # Show I/O schedulers
volt tune io scheduler /dev/sda --scheduler mq-deadline
volt tune io limit <workload> --read-bps 500M --write-bps 200M

volt tune net

Network tuning.

volt tune net show                     # Show network tuning
volt tune net buffers --rmem-max 16M --wmem-max 16M

---

Shortcuts

These resolve to their canonical commands. They exist where intent is unambiguous.

Shortcut	Equivalent	Notes
volt ps	Unified listing	Shows all workloads
volt run <image>	volt container create --image <image> --start	Quick-start container
volt exec <name> -- <cmd>	volt container exec <name> -- <cmd>	Container exec
volt ssh <name>	volt vm ssh <name>	Only VMs have SSH
volt connect <name>	volt desktop connect <name>	Desktop connect
volt status	volt system info	Platform overview

volt get — List Resources

volt get vms             # volt vm list
volt get containers      # volt container list
volt get services        # volt service list
volt get networks        # volt net list
volt get volumes         # volt volume list
volt get images          # volt image list
volt get nodes           # volt cluster node list
volt get tasks           # volt task list
volt get desktops        # volt desktop list

volt describe — Inspect Resources

volt describe vm myvm              # volt vm inspect myvm
volt describe container web        # volt container inspect web
volt describe service nginx        # volt service inspect nginx
volt describe network backend      # volt net inspect backend
volt describe volume pgdata        # volt volume inspect pgdata

volt delete — Delete Resources

volt delete vm myvm                # volt vm destroy myvm
volt delete container web          # volt container delete web
volt delete service myapp          # volt service delete myapp
volt delete network backend        # volt net delete backend