Usage Guide

Voltis is a system orchestration tool for managing edge devices. It consists of a lightweight daemon that runs on each node and a CLI for remote control. The daemon handles service management, workload deployment, and cluster coordination (e.g., with k3s).

Installation

Building from Source

Clone the repository: git clone https://github.com/voltis-platform/voltis.git
Build the CLI: task build (outputs to ./bin/voltis)
Install: task install (copies to ~/.local/bin/voltis)

Debian Package

Build the package: task build-tools-image && task build-deb
Install: sudo dpkg -i bin/voltis_*.deb

Running the Daemon

The daemon provides the API server, database, and controllers for managing workloads and services.

voltis daemon --store /path/to/voltis.sqlite.db --listen-address :4650

--store: Path to SQLite database (default: /var/lib/voltis/voltis.sqlite.db)
--listen-address: API server address (default: :4650)

The daemon runs in the background, listening for CLI requests. It manages:

Workload storage and activation
Service states (active/inactive via systemd)
Jobs and packages
Periodic reconciliation (every 3 seconds by default)

CLI Commands

Set VOLTIS_API_ADDRESS environment variable to point to your daemon (default: http://localhost:4650).

Basic Commands

voltis ping: Test connectivity to the daemon.
voltis health: Check daemon health.
voltis version: Display CLI version info.
voltis components list: List installed components (services, packages, jobs).

Workload Management

Workloads define sets of services to install and manage. A workload directory must contain voltis.toml (config) and *.voltis.taskfile.yml files (tasks for install/uninstall/state).

Building a Workload File

voltis workload buildfile /path/to/workload-dir --output workload.tar.gz

Creates a gzipped tarball from the directory.
Requires voltis.toml in the root.

Pushing a Workload

voltis workload push workload.tar.gz --name my-workload --status active

Uploads the tarball to the daemon.
--name: Workload name (default: workload-1).
--status: active (start services) or inactive (install but don’t start).

Building and Pushing a Workload File (In one line)

voltis workload build /path/to/workload-dir --name my-workload --status active

Creates a workload from a directory and pushes to Voltis
Can set name with --name or -n flag
Can set to be active workload with --status active
Requires voltis.toml in the root.

Listing Workloads

voltis workload list

Shows workloads with name, digest, active status, reconcile status, and messages.

Activating a Workload

voltis workload active --name my-workload

Sets the workload as active, starting its services.

Modifying Workload Reconcile

voltis reconcile start

Starts reconcile to be started on the active workload. Can also be stop to stop reconcile on the active workload.

Resetting

voltis workload reset

Uninstalls and removes the active workload.

Deleting

voltis workload delete --name my-workload

Deletes the workload and will uninstall if active.

Service Management

Services are defined in workloads via voltis.toml and taskfiles.

voltis service list

Lists services with current/desired state, installed status, and messages.

Package and Job Management

voltis package list: Lists installed packages.
voltis job list: Lists jobs with completion status.

Workload Structure

voltis.toml

Configures services and packages with their install/uninstall order:

version = "1"
workload = "my-workload"

installOrder = ["service1", "package1"]
uninstallOrder = ["package1", "service1"]

[services.service1]
state = "active"
systemdUnitName = "service"

[packages.package1]

state: active (start via systemd) or inactive (install only).
systemdUnitName for identification.
packages are automatically installed and reconcile based on the workload setting.

Taskfile (e.g., service1.voltis.taskfile.yml)

Defines install/uninstall/state tasks using Task syntax:

version: "3"
tasks:
  action.install:
    desc: Install service1
    status:
      - which service1
    cmds:
      - apt install -y service1
  action.uninstall:
    desc: Uninstall service1
    status:
      - "! which service1"
    cmds:
      - apt remove -y service1
  state.active:
    desc: Start service1
    precondition:
      - which service1
    cmds:
      - systemctl start service1
  state.inactive:
    desc: Stop service1
    precondition:
      - which service1
    cmds:
      - systemctl stop service1

Optional extras/service1.service for custom systemd units.

API Usage (Direct HTTP)

The daemon exposes a REST API at http://<address>:4650.

GET /health: Health check.
POST /ping: Ping test.
GET /workload: List workloads.
POST /workload/{name}/status/{active|inactive}: Push workload tarball.
POST /active/{name}: Activate workload.
POST /reconcile/status/{start|stop}: Modify workload reconcile status.
POST /reset: Reset active workload.
GET /service: List services.
GET /package: List packages.
GET /job: List jobs.

Use tools like curl for direct interaction.

Development

Run tests: task test
Lint: task lint
Serve docs site: task serve-site (at http://localhost:1313)

For more details, see the source code.

Understanding the Basics Workloads